A-Task API

一、Introduction

1、Callback Usage

所有的任务在默认情况下，处理成功将回调onCompleted(result)方法，失败将回调onError(xlinkCoreException)方法

当返回错误时，通过错误信息可以获取错误码及异常信息，以提供调试帮助或者是用户提示上的说明。

public void onError(XLinkCoreException ex){
    //获取错误码
    int code = ex.getErrorCode();
    //获取错误信息对象,包括错误码与错误说明
    XLinkErrorDesc errorDesc = ex.getErrorDesc();
    //错误码名称(英文)
    String name = ex.mErrorName;
    //错误码说明(中文)
    String desc = ex.mErrorDesc;
     
    //快捷获取错误码名称或说明
    String name = ex.getErrorName();
    String desc = ex.getErrorDescStr();
 
    //当错误为未知错误时，可能存在原始错误码，可以查看是否存在某原始的错误码
    //这是由于某些错误码可能在当前版本不兼容或不存在，或者可能是云端返回的 API 错误码暂时未同步
    if(code == XLinkErrorCodes.ERROR_UNKNOWN){
        int srcErrorCode = ex.getSourceErrorCode();
    }
 
    //当异常信息为其它异常或者未知异常时，有可能存在原始异常信息，也可以获取到处理
    if (code == XLinkErrorCodes.ERROR_OTHER_EXCEPTION)
            Throwable srcSrc = ex.getSrcThrowable();
            if (srcSrc != null) {
                //原始的异常信息
            }
        }
    }   
}

注意事项：
1.当回调错误时，异常信息是必然存在的，不为空
2.每个异常必定存在一个错误码及错误信息，错误信息不为空

2、Erorr Codes

所有错误码主要分为两类：

  • 一类是通用的错误码，即可能在任何任务中出现的错误码，该部分的错误码一般情况下是没有对应的解决方案，通常可以通过重试任务尝试解决（也存在一些错误码在出现时是必定无法正常使用，即使重试也是一样的结果）
  • 另一类是对应不同的任务可能出现的错误码，如一些设备错误码不可能出现在与用户相关任务中。

注意事项：
1.所有包含 CLOUD 的错误码都是与云端通讯有关的
2.所有未说明解决方案的说明该错误无法进行处理，可尝试重试
3.绝大部分的错误码是不会抛出（SDK 内部会进行处理），这里仅是列出所有理论上任务中可能抛出的错误码，所有错误码请参考 APP-SDK错误码

通用部分的错误码，并附上大致说明与一些解决方案，特定错误码在后续具体任务中说明，不在此处一一列出：

错误码 说明 建议解决方案
TASK_TIMEOUT 任务超时 重试操作
TASK_CANCELED 任务取消 -
ERROR_UNKNOWN 未知错误 建议通过工单报告错误码或者更详细说明错误发生情况,如有源错误码可一并提供，可以尝试重试操作
ERROR_API_UNKNOWN 未知的API错误,或者解析API错误码时出错 建议通过工单报告错误码
ERROR_OTHER_EXCEPTION 其它的异常信息 通过查看原始异常信息确定解决方案
ERROR_SOCKET_TIMEOUT socket 连接超时 检查网络后重试操作
ERROR_OPERATION_NOT_SUPPORTED 当前操作不支持无法执行 -
PROTOCOL_VERSION_NOT_SUPPORTED 协议版本不支持 -
DEVICE_FAIL_DEVICE_NOT_EXIST 设备对象不存在 -
DEVICE_FAIL_DEVICE_ID_IS_ZERO 设备ID不能为0 -
PARAMS_INVALID 参数不合法 确认参数有效再重试
PARAMS_NOT_EXIST 需要的参数不存在 确认参数有效再重试

3、ask Type

所有任务主要是与设备通讯的任务，但是有一部分任务是通过接口请求处理的，在该类任务中只会出现 API 错误码而不会出现其它的给定的错码误。所有 API 错误码请参考APP-SDK错误码

任务类型 说明
http任务 仅通过 HTTP 接口通讯的任务，只返回与 API 有关的错误码
普通任务 包含使用 MQTT 协议通讯的任务（可能存在 HTTP 通讯），同时可能返回 API 错误码或 SDK 错误码

在下述任务中，未进行特殊说明的情况下，设置参数时调用的方法都是添加前缀set

4、Task Default Timeout

在 SDK 中，主要的任务都是有固定默认的超时时间，该时间只是作为一个参考时间，开发者可根据实际的情况（如网络环境或使用场景）自行修改。

任务 默认时间（ms） 任务说明
XLinkScanDeviceTask 45000 扫描设备任务
XLinkAddDeviceTask 45000 添加设备任务
XLinkUserAuthorizeTask 30000 普通用户登录任务
XLinkThirdPartyAuthorizeTask 30000 第三方用户登录任务
XLinkSmsAuthroizeTask 30000 手机短信登录任务
XLinkRefreshTokenTask 30000 新快捷登录任务
XLinkRemoveDeviceTask 30000 移除设备任务
XLinkSyncDeviceListTask 30000 同步设备列表任务
XLinkSyncHomeDeviceListTask 30000 同步单个Home设备列表任务
XLinkTMLSetAttributeTask 10000 设置物模型属性任务
XLinkTMLInvokeServiceTask 10000 调用物模型服务任务
XLinkTMLProbeAttributeTask 10000 获取物模型任务
XLinkProbeDataPointTask 10000 探测数据端点任务
XLinkShareDeviceTask 30000 分享设备任务
XLinkHandleShareDeviceTask 30000 处理分享操作任务
XLinkConnectDeviceTask 30000 连接设备任务

5、Reference

以下为任务中的关联的Class及相关说明

类名 类型 说明
XLinkSendDataPolicy 枚举类 通讯策略
XLinkRestfulEnum.UserSource 枚举类 用户来源
XLinkRestfulEnum.ShareMode 枚举类 分享模式
XLinkRestfulEnum.DeviceAuthority 枚举类 设备控制权限
XLinkHandleShareDeviceTask.Action 枚举类 分享设备处理操作
XLinkConstant 常量类 所有常用的常量将存在于此类中，包括常用的flag和部分默认参数值，详情请查看 API-XLinkConstant

二、User Info Task

1、XLinkUserAuthorizeTask

本任务用于物联云平台的账号（ demo 中注册或者是已有的 APP 账号）登录授权

  • 任务名称:XLinkUserAuthorizeTask
  • 任务类型:HTTP任务
  • 参数说明:
参数 类型 说明 是否必须
phone String 手机号 使用手机账号登录时必须填写
phoneZone String 手机区号 否，默认为+86（自v6.2版本起）
email String 邮箱 使用邮箱账号登录时必须填写
password String 密码 是
corpId String 企业ID 是
timeout int 超时时间 否，默认超时时间请查看本文档的第一章节的第4小点【Task Default Timeout】
listener TaskListener 监听事件 是
  • 返回数据:UserAuthApi.UserAuthResponse
{
    "userId":0,//用户ID
    "accessToken":"token",//授权信息
    "refreshToken":"refreshToken",//授权信息过期时用于刷新授权信息
    "expireIn":7200,//授权信息有效时间,单位秒
    "authorize":"xxx"//云端CM登录授权信息
}

注意事项：登录的账号为 APP 的账号，不是企业账号，可以通过调用接口或者 demo 进行注册获取

2、XLinkSmsAuthorizeTask——自v6.2版本起

本任务用于短信验证码登录账号

  • 任务名称:XLinkSmsAuthorizeTask
  • 任务类型:HTTP任务
  • 参数说明:
参数 类型 说明 是否必须
corpId String 企业ID 是
phone String 手机号 用于登录的手机号
phoneZone String 手机区号 否，默认为+86
verifyCode String 短信验证码 是
timeout int 超时时间 否
listener TaskListener 监听事件 是
  • 返回数据:UserAuthApi.UserSmsAuthResponse
{
    "userId":0,//用户ID
    "accessToken":"token",//授权信息
    "refreshToken":"refreshToken",//授权信息过期时用于刷新授权信息
    "expireIn":7200,//授权信息有效时间,单位秒
    "authorize":"xxx"//云端CM登录授权信息
}

注意事项：
1.短信验证码需要提前通过接口获取到
2.若未注册过的手机号将会自动注册账号

3、XLinkThirdPartyAuthorizeTask

本任务用于第三方接入物联云平台的账号登录授权

  • 任务名称:XLinkThirdPartyAuthorizeTask
  • 任务类型:HTTP任务
  • 参数说明:
参数 类型 说明 是否必须
openId String 第三方账号换取的openId 是
accessToken String 第三方账号换取的token 是
source enum 第三方账号来源 是，类型请参考附录1
name String 昵称 否
timeout int 超时时间 否
listener TaskListener 监听事件 是
  • 返回数据:ThirdPartyAuthApi.AuthResponse
{
    "userId":0,//用户ID
    "accessToken":"token",//授权信息
    "refreshToken":"refreshToken",//授权信息过期时用于刷新授权信息
    "expireIn":7200,//授权信息有效时间,单位秒
    "authorize":"xxx"//云端CM登录授权信息
}

4、XLinkRefreshTokenTask——自v6.2版本起

本任务用于刷新凭证授权，根据开发指南及上述登录任务说明，登录后将返回的用户信息主要有几个字段，其中包括了accessToken——用于用户请求授权凭证，以及refreshToken刷新授权凭证——用于刷新用户请求授权凭证。

通过刷新授权凭证即可获取到新的用户请求授权凭证，用于其它正常的请求处理了。本任务可用于快捷登录，详情请参考进阶篇-用户授权管理

  • 任务名称:XLinkRefreshTokenTask
  • 任务类型:HTTP任务
  • 参数说明:
参数 类型 说明 是否必须
refreshToken String 用户的刷新凭证 是
userId int 用户ID,用于 CM 服务器登录 是
authString int CM 服务器授权信息,用于 CM 服务器登录 是
xlinkUser XLinkUser 此参数为上述所有参数的集合体,与上述所有参数二择一即可 否
timeout int 超时时间 否
listener TaskListener 监听事件 是
  • 返回数据:UserApi.TokenRefreshResponse
{
    "access_token":"token",//授权信息
    "refresh_token":"refreshToken",//授权信息过期时用于刷新授权信息
    "expire_in":"7200"//授权信息有效时间,单位秒
}
  • 调用方式：

刷新 token 时必须的参数是 refreshToken、userId、authString，该部分的参数都可以通过 XLinkUser 一次性提供。

//直接设置必须参数调用
Task task = XLinkRefreshTokenTask.newBuilder()
    .setRefreshToken(token)
    .setUserId(id)
    .setAuthString(auth)
    .setListener(listener)
    .build();
 
//创建用户对象一次性提供所有参数
XLinkUser user = new XLinkUser();
user.setRefreshToken(token);
user.setUid(id);
user.setAuthString(auth);
 
Tsak task =  XLinkRefreshTokenTask.newBuilder()
    .setXLinkUser(user)
    .setListener(listener)
    .build();

三、Device Control Task

1、XLinkScanDeviceTask

本任务用于扫描局域网中的设备，在设备扫描到后才可以进行设备的订阅操作

  • 任务名称:XLinkScanDeviceTask
  • 任务类型:普通任务
  • 参数说明:
参数 类型 说明 是否必须
productIds List 产品ID，用于过滤扫描到的设备 是
filterDevices boolean 是否过滤设备，每个扫描到的设备仅会回调一次 否，默认值为 false
totalTimeout int 总超时时间 否
scanDeviceListener XLinkScanDeviceListener 扫描设备监听回调 是
listener TaskListener 与scanDeviceListener相同，使用一个回调即可，重置设置时注意两者会互相覆盖 否
  • 返回数据:使用 scanDeviceListener 时，回调在onScanResult(XDevice)，设备数据类型请参考API-XDevice
  • 错误码
错误码 说明
TASK_TIMEOUT 任务超时

注意事项：
1.扫描设备时 APP 需要与设备在同一局域网中
2.扫描任务未取消任务的情况下，扫描任务总是会超时

2、XLinkAddDeviceTask

本任务用于在扫描到设备之后，添加并订阅设备

  • 任务名称:XLinkAddDeviceTask
  • 任务类型:普通任务
  • 参数说明:
参数 类型 说明 是否必须
xDevice XDevice 添加的设备对象 是
connectLocal boolean 是否添加后进行本地连接，仅需要云端连接时，可以设置为false 否，默认为true
needSubscription boolean 是否需要订阅设备，当需要绑定当前用户与设备关系时，设置为true 否，默认为true
totalTimeout int 总超时时间 否
pinCode byte[] 校验码 否
ticket byte[] 校验码,兼容旧数据 否，推荐忽略
listener TaskListener 监听事件 是
  • 返回数据:XDevice，添加成功将返回设备对象，设备数据类型请参考API-XDevice
  • 错误码:
错误码 说明
基本错误码 按上述基本错误码说明处理
SUBSCRIBE_DEVICE_FAIL_DEVICE_INFO_INVAILD 设备信息无效，请确认后台填写了有效的设备信息，是否未将设备添加到产品列表下
SUBSCRIBE_DEVICE_FAIL_TICKET_INVAILD 云端订阅设备失败，Ticket校验失败
SUBSCRIBE_DEVICE_FAIL 订阅失败，服务器内部错误，建议提供日志反馈工单
SUBSCRIBE_DEVICE_FAIL_DEVICE_MODE_LIMITED 设备订阅模式问题，请确认后台是否允许多人订阅
PAIRING_LOCAL_FAIL_REACH_PAIRING_LIMIT 配对次数达到16次，请重置设备后重新尝试
PAIRING_HANDSHAKE_LOCAL_FAIL_DEVICE_NOT_READY 设备不在配对状态

自v6.2版本起，提供了新的订阅方式，以下为新订阅方式中可能返回的错误码

新错误码 说明
SUBCODE_STATE_CLOUD_FAIL_SERVER_SUBSCRIBE_FAIL 云端执行订阅时发生错误
SUBCODE_STATE_CLOUD_FAIL_DEVICE_MODE_LIMITED 设备订阅模式问题，请确认后台是否允许多人订阅
SEND_SUBCODE_LOCAL_FAIL_REFUSE 设备拒绝被订阅，请确认是否开启订阅开关
SEND_SUBCODE_LOCAL_FAIL_REACH_PAIRING_LIMIT 设备配对次数达上限
SEND_SUBCODE_LOCAL_FAIL_DECRYPT 设备解密出错，订阅码无法正确解析

注意事项：
1.添加设备时根据不同的网络情况与设备硬件，可能需要的时间是不同的，根据情况为添加设备操作设置自主的超时时间
2.添加设备为 APP 与设备进行连接，并产生关联关系；订阅设备为将 APP 与设备的关联关系绑定并提交到云端存储，二者存在一定差异性，详情可参考 FAQ
3.自v6.2版本起，提供了新的订阅方式，详情请查看进阶篇-设备订阅关系管理

3、XLinkConnectDeviceTask——自v6.2版本起

本任务用于将设备添加到设备管理列表中进行维护或者是切换设备的连接策略，在v6版本 SDK 中，大部分情况下不需要使用此任务，此任务更多是用于辅助使用的功能。通常情况下设备的状态变更都建议通过监听设备的状态回调——XLinkDeviceStateListener进行处理。

此任务的特点是通过任务连接的设备，在给定超时时间内如果能成功按相应的连接策略连接成功，则返回结果；否则返回错误。但是不管结果是否成功，设备都会添加到设备管理列表中维护，即使设备是当给定时间内无法连接成功，后续也可能是连接成功的。

另一个可能需要使用到此任务的场景是需要改变设备的连接策略。在绝大部分情况下应该都不需要手动强制改变连接策略，当需要时，可通过此任务进行操作。同时，通过设备管理对象也可以直接进行切换设备的连接策略，只是处理和调用方式与此任务不同而已，详情请查看进阶篇-设备连接状态管理

  • 任务名称:XLinkConnectDeviceTask
  • 任务类型:普通任务
  • 参数说明:
参数 类型 说明 是否必须
xDevice XDevice 需要连接的设备对象 是
connectionFlags int 连接策略 否
timeout int 超时时间 否
listener TaskListener 监听事件 是
  • 返回数据：XDevice，连接成功返回的设备对象，设备数据类型请参考API-XDevice
  • 错误码：TASK_TIMEOUT，连接失败时为超时

注意事项：
1.当设备不在管理列表中时，会将设备添加到管理列表中处理；当设备在管理列表中时，使用该设备相关的信息
2.连接策略允许不设置，不设置时使用当前设备管理列表中的连接策略进行处理
3.设备不管是否连接成功都会存在设备管理列表中，即使任务返回失败后续也会持续维护设备状态，依然有可能连接成功

  • 连接策略
    连接策略在常量类XLinkConstant中定义
字段 意义 说明
FLAG_POLICY_NONE_CONNECTION 无连接策略 不进行任何处理，延用当前设备状态
FLAG_POLICY_AUTO_CONNECTION 进行云端、内网自动连接 当设备云端或内网断开时，尝试自动重新连接
FLAG_POLICY_LOCAL_AUTO_CONNECTION 内网自动连接 当设备内网状态断开时会尝试进行自动连接
FLAG_POLICY_LOCAL_ONCE_CONNECTION 内网一次性连接 当设备内网状态断开后不会再进行连接，切换为此连接策略时，不影响当前内网的连接状态
FLAG_POLICY_CLOUD_AUTO_CONNECTION 云端自动连接 当设备云端状态断开时会尝试进行自动连接
FLAG_POLICY_CLOUD_ONCE_CONNECTION 云端一次性连接 当设备云端状态断开后不会再进行连接，切换为此连接策略时，不影响当前云端的连接状态 
XLinkConnectDeviceTask task = XLinkConnectDeviceTask.newBuilder()
        //设置连接设备
        .setXDevice(device)
        //设置连接策略，多个连接策略可通过或操作合并在一起
        .setConnectionFlags(XLinkConstant.FLAG_POLICY_LOCAL_ONCE_CONNECTION |
        XLinkConstant.FLAG_POLICY_CLOUD_AUTO_CONNECTION)
        .setListener(listener)
        .build();
XLinkSDK.startTask(task);

4、XLinkTMLSetAttributeTask

本任务用于控制设备，设置设备的物模型属性从而使设备状态或者行为发生变化

  • 任务名称: XLinkTMLSetAttributeTask
  • 任务类型:普通任务
  • 参数说明:
参数 类型 说明 是否必须
xDevice XDevice 操作的设备对象 是
totalTimeout int 总超时时间，超时时任务结束 否
sendPolicy XLinkSendDataPolicy 临时发送策略，可改变此次操作采用当前的发送策略，若未设置使用全局（初始化时）的发送策略 否，默认使用全局的发送策略
payload String json数据的物模型参数 是
listener TaskListener 监听事件 是
  • 返回数据:XDevice，设置成功将返回设备对象，设备数据类型请参考API-XDevice

注意事项：通常情况下，设置属性物模型属性需要设备状态在线（即能成功与设备进行通讯）

5、XLinkTMLInvokeServiceTask

本任务用于控制设备，设置设备的物模型服务从而使设备状态或者行为发生变化

  • 任务名称: XLinkTMLInvokeServiceTask
  • 任务类型:普通任务
  • 参数说明:
参数 类型 说明 是否必须
xDevice XDevice 操作的设备对象 是
totalTimeout int 总超时时间，超时时任务结束 否
sendPolicy XLinkSendDataPolicy 临时发送策略，可改变此次操作采用当前的发送策略，若未设置使用全局（初始化时）的发送策略 否，默认使用全局的发送策略
serviceName String 物模型服务名称 是
payload String json数据的物模型参数 是
listener TaskListener 监听事件 是
  • 返回数据:XDevice，设置成功将返回设备对象，设备数据类型请参考API-XDevice

注意事项：通常情况下，设置属性物模型服务需要设备状态在线（即能成功与设备进行通讯）

6、XLinkTMLProbeAttributeTask

本任务用于获取设备物模型，通常设备状态或行为是从物模型表现出来的，根据物模型可以获取到设备不同的数据或者状态

  • 任务名称: XLinkTMLProbeAttributeTask
  • 任务类型:普通任务
  • 参数说明:
参数 类型 说明 是否必须
xDevice XDevice 操作的设备对象 是
totalTimeout int 总超时时间，超时时任务结束 否
sendPolicy XLinkSendDataPolicy 临时发送策略，可改变此次操作采用当前的发送策略，若未设置使用全局（初始化时）的发送策略 否，默认使用全局的发送策略
listener TaskListener 监听事件 是
  • 任务执行成功后，物模型结果将会在XLinkTMLDeviceAttributeListener回调，所以需要在初始化SDK的时候配置好setTMLAttributeListener

注意事项：通常情况下，获取数据端点需要设备状态在线（即能成功与设备进行通讯）

7、XLinkRemoveDeviceTask

本任务用于删除掉当前 SDK 维护的设备对象，并且取消当前用户与该设备的绑定关系

  • 任务名称:XLinkRemoveDeviceTask
  • 任务类型:HTTP任务
  • 参数说明:
参数 类型 说明 是否必须
xDevice XDevice 操作的设备对象 是
userId int 用户ID 否，不推荐设置，默认使用当前登录用户的id
timeout int 超时时间 否
listener TaskListener 监听事件 是
  • 返回数据:String，移除成功返回空字符串，移除失败返回错误信息
  • 错误码:
错误码 说明
基本错误码 按上述基本错误码说明处理
API错误码 -

注意事项：删除设备会取消掉当前用户与该设备的绑定关系，即云端不再保存二者的绑定关系，删除设备成功后再次同步设备列表时将不会出现已删除的设备

8、XLinkSyncDeviceListTask

本任务用于从云端后台同步，同步当前用户账户绑定的设备对象，同步下来的设备对象在设备正常可用时，则可以通过云端进行设备控制

  • 任务名称:XLinkSyncDeviceListTask
  • 任务类型:HTTP任务
  • 参数说明:
参数 类型 说明 是否必须
connectLocal boolean 同步设备列表后是否进行设备本地连接 否，默认 true
userId int 用户ID 否，不推荐设置，默认使用当前用户 id
version int 版本号 否，不推荐设置
timeout int 超时时间 否
listener TaskListener 监听事件 是
  • 返回数据:XDevice，设置成功将返回设备对象，设备数据类型请参考API-XDevice
  • 错误码:返回 API 错误码或超时

注意事项：
1.同步的设备列表中的所有设备都是与当前用户存在绑定关系，无绑定关系的设备将不会同步到
2.默认情况下同步后的设备会自动进行云端与内网连接，

9、XLinkShareDeviceTask

本任务用于进行设备分享操作，并返回是否分享成功的结果

  • 任务名称:XLinkShareDeviceTask
  • 任务类型:HTTP任务
  • 参数说明:
参数 类型 说明 是否必须
xDevice XDevice 分享的设备对象 是
openId String 第三方账号openId 是，分享第三方账号必须设置，普通账号不需要
openIdSource XLinkRestfulEnum.UserSource 第三方账号来源 是，分享第三方账号必须设置，普通账号不需要
account String 分享账号 是，与第三方账号互斥，普通账号分享必须设置
mode XLinkRestfulEnum.ShareMode 分享类型 是，分享模式
authority XLinkRestfulEnum.DeviceAuthority 设备操作权限 否，默认允许读写
expired int 分享码有效期，单位秒 否，默认7200s
uid int 分享的目标用户id 是
timeout int 超时时间 否
listener TaskListener 监听事件 是

注意事项：
1.设备分享目标账号可以是普通账号，也可以是第三方账号，注意两者是分享是互斥的
2.openId、openIdSource 都是第三方账号分享使用的参数
3.account、uid 为普通账号分享使用的参数，根据分享模式选择不同的参数

10、XLinkHandleShareDeviceTask

本任务用于处理设备分享消息

  • 任务名称:XLinkHandleShareDeviceTask
  • 任务类型:HTTP任务
  • 参数说明:
参数 类型 说明 是否必须
inviteCode String 分享码 是
action XLinkHandleShareDeviceTask.Action 分享操作行为 是
uid int 当前用户ID 否，默认为当前用户id
timeout int 超时时间 否
listener TaskListener 监听事件 是
  • 返回数据:String，处理成功返回空字符串，处理失败返回错误
  • 错误码:返回 API 错误码或超时

四、Other Task

1、XLinkLocalSendTriggerUpgradeTask-自6.2.6.x版本起

本任务用于内网固件升级时，向设备发送触发检测升级任务的指令。关于内网固件升级操作，请参考进阶篇-设备固件升级

  • 任务名称：XLinkLocalSendTriggerUpgradeTask
  • 任务类型：普通任务
  • 参数说明：
参数 类型 说明 是否必须
firmwrareType byte 固件类型 是
xDevice XDevice 设备对象 是
timeout int 超时时间 否
listener TaskListener 监听事件 是
  • 固件类型
    固件类型在XLinkConstant常量类中定义
字段 意义
FIRMWARE_TYPE_WIFI WIFI固件类型
FIRMWARE_TYPE_MCU MCU固件类型
  • 返回数据：返回数据为Boolean，表示是否发送指令成功
  • 错误码：返回超时

注意事项：此任务只能确认是否成功发送指令，暂时无法确保指令是否送达；若出现发送成功后短时间内设备无任务操作或反应，则应该考虑重发。

2、XLinkLocalSendUpgradeTaskResultTask-自6.2.6.x版本起

本任务用于内网固件升级时，接收到设备的获取升级任务请求时，返回发送升级任务详细信息。关于内网固件升级操作，请参考进阶篇-设备固件升级

  • 任务名称：XLinkLocalSendUpgradeTaskResultTask
    - 任务类型：普通任务
  • 参数说明：
参数 类型 说明 是否必须
xDevice XDevice 设备对象 是
code byte 请求结果码 是
firmwareType byte 固件版本类型 是
currentVersion short 当前固件版本号 是
targetVersion short 目前升级固件版本号 是
identifyCode int 识别码 是
taskId String 任务ID 是
fileMd5 byte[] 固件文件md5值 是
fileSize long 固件文件字节长度 是
url String 固件文件下载地址 是
timeout 超时时间 否
listener TaskListener 监听事件 是
  • 固件类型
    固件类型在XLinkConstant常量类中定义
字段 意义
FIRMWARE_TYPE_WIFI WIFI固件类型
FIRMWARE_TYPE_MCU MCU固件类型
  • 返回数据：返回数据为Boolean，表示是否发送成功
  • 错误码：返回超时

注意事项：
1.部分信息来自固件请求任务的信息中，如当前固件的版本号、识别码
2.固件文件下载地址为内网可访问的URL，并且必须为完整的文件下载地址
3.此任务只能确认指令是否发送成功，暂时无法确保指令送达

五、Relevant Class

以下为此类中的关联类或内部类

1、XLinkSendDataPolicy

数据通讯策略

字段名 说明
AUTO 自动选择发送数据通讯，根据 RTT （往返时延）选择通道，通常情况下内网已连接时会选择选择内网通讯
LOCAL_ONLY 只尝试从内网发送
CLOUD_ONLY 只尝试从外网发送
LOCAL_FIRST 尝试从内网发送，失败则尝试外网发送
CLOUD_FIRST 尝试从外网发送，失败则尝试从内网发送

2、XLinkRestfulEnum.UserSource

用户登录来源

字段名 说明
WEB 网页登录
ANDROID android客户端登录
IOS ios客户端登录
WEIXIN 微信登录
QQ QQ登录
WEIBO 微博登录
FACEBOOK fackbook登录
TWITTER twitter登录
OTHER 其它第三方平台登录

3、XLinkRestfulEnum.ShareMode

分享模式

字段名 说明
ACCOUNT 通过用户ID分享
QR_CODE 二维码方式分享
EMAIL 邮件方式分享

4、XLinkRestfulEnum.DeviceAuthority

设备控制权限

字段名 说明
R 只读
W 只写
RW 可读写
HID 取消权限，对成员取消设备的权限后，成员不再允许使用该设备，自v6.2.7.10版本起（以云端提供功能为准）

5、XLinkHandleShareDeviceTask.Action

设备分享操作

字段名 说明
ACCEPT 接受分享
DENY 拒绝分享
CANCEL 取消分享操作
DELETE 删除分享消息
ACCEPT_QRCODE 接收二维码

六、更新日志

日期 更新内容
2019-05-27 新增连接策略任务的调用示例代码，新增家庭设备权限枚举参数
2019-01-15 自v6.2.6.x版本起，新增内网固件升级任务
2018-09-17 更新v6.2版本新增任务及说明
2018-08-21 新增 API 参数类型，更新部分说明
没找到需要的文档？
你可以提交工单反馈 或 阅读常见问题
客服工单常见问题